D3 Claim Examples

In the section below we will outline each of the asserted and inferred device types.

Asserted Claim Types

Asserted Claim Relationships

D3 claim dependency graph

Overview:

Types are the core of the claim assertion structure
A type can inherit the propertied of many other types
A type can reference one behaviour
A behaviour can be referenced by many types
A behaviour can describe many rules
A rule can be expected malicious=false(default) or malicious malicious=true
A behaviour can inherit rules from multiple behaviours
A type can have many firmwares
A firmware can be referenced by many device types
A device may have many vulnerabilities
A vulnerability can be referenced by many device types

D3 Claim Meta

Each D3 claim will have the following properties:

id: (optional) used to refer to the claim, typically a URI
type: (required) information related to the type of credential this is
credentialSubject: (required) the entity about which a claim is being made, for our purposes this is the payload of the claim
issuanceDate: (optional) date on which it was issued (ISO compliant time string)
issuer: (optional) entity making the claim
proof: (optional) typically provided by the issuer as a method to verify the claim is genuine

The credentialSubject will encapsulate the payload of the claim i.e. the data associated with the claim type.

JSON Schema

{
  "$id": "https://example.com/d3-claim.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "d3-claim",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "d3-device-type-behaviour",
        "d3-device-type-assertion",
        "d3-device-type-inheritance",
        "d3-device-type-vuln",
        "d3-firmware-assertion"
      ],
      "description": "D3 claim type"
    },
    "credentialSubject": {
      "type": "object",
      "description": "Automatically generated credential subjects for each type"
    },
    "id": {
      "type": "string",
      "description": "The credential id, typically a URI"
    },
    "issuer": {
      "type": "string",
      "description": "The credential issuer"
    },
    "issuanceDate": {
      "type": "string",
      "description": "ISO timestamp of when the claim was issued"
    },
    "proof": {
      "type": "string",
      "description": "Evidence related to how the credential was derived"
    }
  },
  "required": ["type", "credentialSubject"]
}

YAML D3 Claim Example

type: d3-device-type-vuln  # D3 claim type
credentialSubject:  # information follwing the schema for the claim type (a vulnerability in this case)
  id: 7bb6ec6d-0514-4a2d-91b9-aed1cee34ef9  # GUID
  # Link to the source of a vulnerability preferably on NIST NVD, or CVE
  vulnerability: https://nvd.nist.gov/vuln/detail/CVE-2018-11581
issuer: CertFarm Ltd.  # (optional) Verified crediential issuer

Device Type Assertion

About Type Claims

Asserting a device type is claim that an abstract device type exists, where every instance of that device type are assumed to be identical (excepting a few unique parameters like MAC address, at the discretion of the ManySecured routers use)

Sets of device type assertion come from external trusted authorities.

Practically, a D3 type claim residing on the primary D3 github repo, does not need signing. It is deemed to be signed by the collective community

Sources of device type assertions

Manufacturer: a manufacturer may assert their own device types
User: individual users may asset the existing of a device (crowd sourcing)
Independent organisations: some other 3rd party

JSON Schema

{
  "$id": "https://example.com/type.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "type",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "GUID for the device type"
    },
    "parents": {
      "type": "array",
      "description": "Parent types to inherit from",
      "items": {
        "type": "object",
        "description": "Parent type to inherit from",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "GUID for the parent device type"
          },
          "properties": {
            "type": "array",
            "description": "List of properties to inherit by name, if none specified, will inherit all parent properties",
            "items": {
              "type": "string",
              "description": "Name of property to inherit"
            }
          }
        },
        "required": ["id"]
      }
    },
    "aliases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of aliases for the device type"
    },
    "manufacturer": {
      "type": "string",
      "description": "The manufacturer name"
    },
    "manufacturerUri": {
      "type": "string",
      "format": "uri",
      "description": "The manufacturer URI path"
    },
    "modelNumber": {
      "type": "string",
      "description": "The model number of the device type"
    },
    "modelSupportUri": {
      "type": "string",
      "format": "uri",
      "description": "The model support URI of the device type"
    },
    "modelInformationUri": {
      "type": "string",
      "format": "uri",
      "description": "The model information URI of the device type"
    },
    "name": {
      "type": "string",
      "description": "The device type name"
    },
    "tags": {
      "type": "string",
      "pattern": "^#\\w+$|(#\\w+( |, |,))+#\\w+$",
      "description": "The array of strings with tags space or comma separated tags",
      "examples": [
        "#tag1",
        "#tag1 #tag2",
        "#tag1,#tag2",
        "#tag1, #tag2"
      ]
    },
    "macAddresses": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of MAC addresses"
    },
    "behaviour": {
      "type": "string",
      "description": "The behaviour name or id for this device type"
    },
    "vulnerabilities": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of vulnerability IDs"
    },
    "firmwares": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of firmware IDs"
    },
  },
  "required": ["id"]
}

YAML Example

type: d3-device-type-assertion
credentialSubject:
  id: abec4794-bd0f-4573-9f2d-6ff689e1e0c1
  aliases:
    - "www.example.com/aa92ebae-4928-4456-b597-cbd7657e9e83"
    - "www.example-corp.com/aa92ebae-4928-4456-b597-cbd7657e9e83"
  manufacturer: Example Corp.
  manufacturerUri: https://example.com/
  modelNumber: A1357
  modelSupportUri: https://example.com/product/A1357
  modelInformationUri: https://example.com/product/A1357/support
  name: Example Device A1357
  tags: "#iot,#sensor"
  macAddresses:
    - 00:00:00:00:00:00/36  # MAC address of the device with /bitRange which IDs the manufacturer
  behaviour: 97c4fb11-5fb8-44c3-b449-107fdbb66a15  # GUID of behaviour to use
  vulnerabilities:  # list of vulnerability GUIDs
    - da03d559-d0f4-4bf5-8924-f3c41e759283
  firmwares:  # list of GUIDs of compatible firmwares
    - f3b12425-bbdc-4a04-8eb6-8b5b9b4dc88a
  behaviour: 97c4fb11-5fb8-44c3-b449-107fdbb66a15  # GUID of behaviour to use
  parents:
    - id: ba3ba36d-be70-40f0-9c52-95b560066d11 # Id of parent type to inherit from
      # Specific properties to inherit (optional, default inherit all properties)
      properties:
        - manufacturer
        - manufacturerUri
        - tags
issuer: CertFarm Ltd. # (optional) Verified crediential issuer

Linking a Behaviour

The behaviour of a device is referenced by the ID of the behaviour claim describing the behviour for the device type. In the example above, the line:

  behaviour: 97c4fb11-5fb8-44c3-b449-107fdbb66a15  # GUID of behaviour to use

Specifies that the behaviour of this device is described by the behaviour claim with id 97c4fb11-5fb8-44c3-b449-107fdbb66a15.

As behaviours can be aggregated through inheritance, a device should refer to one-and-only-one behaviour claim.

Linking Vulnerabilities and Firmware

Firmware and Vulnerabilities can be associated with a device type by referencing the IDs (as a list) of the firmware and vulnerabilities you want to associate with the type. In the example above, the firmware and vulnerabilites are linked with the following lines:

  vulnerabilities:  # list of vulnerability GUIDs
    - da03d559-d0f4-4bf5-8924-f3c41e759283
  firmwares:  # list of GUIDs of compatible firmwares
    - f3b12425-bbdc-4a04-8eb6-8b5b9b4dc88a

Inheriting Properties from Parent Type Claims

Device types are hierarchical. All child device types should inherit all properties of their parent.

This allows properties to be expressed efficiently. It also allows for device types to be refined.

Inherited qualities follow the standard rule that you inherit from your parent, unless it is overridden at the child.

Type inheritance my be further qualified if we expect the child to only inherit subset of properties.

Examples of qualified inheritance:

firmware use same firmware
vulnerabilities possess similar vunerabilites
behaviour have same network behaviour
manufacturer inherit manufacturer attributes

At compile time the only requirements is that the reference is provably resolvable.

Embedding Hierarchy Statements

A hierarchy statement may be embedded in the child type.

Types can inherit properties from other types as a list of object referring to the id of the parent type to inherit from and, optionally, the properties to inherit from that type claim. By default, if only the id of the parent is given, all properties should be imported. In the GitHub implementation, you cannot import duplicate keys, the system will throw an error. The snippet from the example above shows several properties being inherited from a parent type.

  parents:
    - id: ba3ba36d-be70-40f0-9c52-95b560066d11 # Id of parent type to inherit from
      # Specific properties to inherit (optional, default inherit all properties)
      properties:
        - manufacturer
        - manufacturerUri
        - tags

Alias

A device type alias is a special case of inheritance where the two types are proven to be identical

::: caution Alias

TODO : this needs fully specifying

:::

Device Behaviour Assertion

About Behaviour Claims

An assertion of device behaviour is a formal claim of the network behaviour we expect form this device (e.g. "the device talks to these services")

A behaviour is a definition of the approved (least privilege) and unapproved internet behaviour expected of this device.

MUD https://datatracker.ietf.org/doc/html/rfc8520 can be used as a the initial basis for that description.

JSON Schema

{
  "$id": "https://example.com/behaviour.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "behaviour",
  "description": "The device behaviour schema in terms of rule id and name",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "GUID for the device behaviour rule"
    },
    "parents": {
      "type": "array",
      "description": "Parent behaviours for the device behaviour",
      "items": {
        "type": "string",
        "format": "uuid",
        "description": "Id of parent behaviour claim to inherit rules from"
      }
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["matches"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the rule"
          },
          "matches": {
            "type": "object",
            "properties": {
              "ip4": {
                "title": "behaviour-ip4",
                "type": "object",
                "description": "The ip v4 protocol behaviour rule",
                "properties": {
                  "sourceIp4": {
                    "type": "string",
                    "format": "ipv4",
                    "description": "The source IPv4 address"
                  },
                  "destinationIp4": {
                    "type": "string",
                    "format": "ipv4",
                    "description": "The destination IPv4 address"
                  },
                  "sourceDnsName": {
                    "type": "string",
                    "description": "The source dns address"
                  },
                  "destinationDnsName": {
                    "type": "string",
                    "description": "The destination dns address"
                  },
                  "protocol": {
                    "type": "number",
                    "description": "The protocol number"
                  }
                }
              },
              "eth": {
                "title": "behaviour-eth",
                "type": "object",
                "description": "The eth protocol behaviour rule",
                "properties": {
                  "sourceMac": {
                    "type": "string",
                    "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
                    "description": "The source MAC address"
                  },
                  "destinationMac": {
                    "type": "string",
                    "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
                    "description": "The destination MAC address"
                  },
                  "etherType": {
                    "type": "number",
                    "description": "The ethernet type field"
                  }
                }
              },
              "tcp": {
                "title": "behaviour-tcp",
                "type": "object",
                "description": "The tcp protocol behaviour rule",
                "properties": {
                  "sourcePort": {
                    "type": "number",
                    "description": "The source port"
                  },
                  "destinationPort": {
                    "type": "number",
                    "description": "The destination ports"
                  }
                }
              },
              "udp": {
                "title": "behaviour-udp",
                "description": "The udp protocol behaviour rule",
                "type": "object",
                "properties": {
                  "sourcePort": {
                    "type": "number",
                    "description": "The source port"
                  },
                  "destinationPort": {
                    "type": "number",
                    "description": "The destination ports"
                  }
                }
              }
            }
          }
        }
      }
    },
    "ruleName": {
      "type": "string",
      "description": "Rule name"
    },
    "malicious": {
      "type": "boolean",
      "description": "Is the behaviour malicious",
      "default": false,
    }
  },
  "required": ["id"]
}

YAML Example with Rules

# The type of the verified credential
type: d3-device-type-behaviour
# Subject if the verfied credential
credentialSubject:
  # The GUID denoting the device rule
  id: aa92ebae-4928-4456-b597-cbd7657e9e83
  # Rules are specified as an array with two keys name and matches
  ruleName: "Example Device Amazon Echo"
  parents:
    - id: fc4d5a51-f985-4de1-a157-51ea9ca5e9c0 # Id of parent behaviour to inherit from
      # Specific rules to inherit from parent behaviour (optional) - all rules inherited by default
      rules:
        - from-ipv4-amazon-1
        - from-ipv4-amazon-4
        - from-ipv4-amazon-6
  rules:
    # The name key string doesn't need to be unique. It is a brief description of the rule
    - name: from-ipv4-amazonecho-0
      # The matches key contains the protocols that need to be matched (eth, ipv4, tcp and udp)
      matches:
        # The ipv4 protocol match contains the `protocol` number key,
        # the source-dnsname, which is a string describing a unique web address
        # the destinationDnsname, which is a string describing a unique web address
        # the source-ipv4, which is a string describing an IPv4 address
        # the destinationIpv4, which is a string describing an IPv4 address
        ip4:
          protocol: 6
          destinationDnsname: dcape-na.amazon.com
        # The tcp protocol match contains the source-port and destination port
        tcp:
          destinationPort: 443
    - name: from-ipv4-amazonecho-1
      matches:
        ip4:
          protocol: 6
          destinationDnsname: softwareupdates.amazon.com
        tcp:
          destinationPort: 443
    - name: from-ipv4-amazonecho-2
      matches:
        ip4:
          protocol: 17
          destinationDnsname: 3.north-america.pool.ntp.org
        udp:
          destinationPort: 123
    - name: from-ipv4-amazonecho-3
      matches:
        ip4:
          protocol: 2
          destinationIp4: 224.0.0.22/32
    - name: from-ipv4-amazonecho-4
      matches:
        ip4:
          protocol: 17
          destinationIp4: 239.255.255.250/32
        udp:
          destinationPort: 1900
    - name: from-ipv4-amazonecho-5
      matches:
        eth:
          destinationMac: ff:ff:ff:ff:ff:ff
          # 0x800 => 2048
          ethertype: 2048
        ip4:
          protocol: 17
          destinationIp4: 255.255.255.255/32
        udp:
          destinationPort: 67
    - name: from-ipv4-amazonecho-6
      matches:
        eth:
          destinationMac: ff:ff:ff:ff:ff:ff
          # 0x800 => 2048
          ethertype: 2048
        ip4:
          protocol: 17
          destinationIp4: 255.255.255.255/32
        udp:
          destinationPort: 67
    - name: from-ipv4-amazonecho-7
      matches:
        ip4:
          protocol: 17
          destinationIp4: 208.67.220.220/32
        udp:
          destinationPort: 53
    - name: from-malicious-sender
      malicious: true
      matches:
        ip4:
          protocol: 17
          destinationIp4: 155.67.220.220/32
        udp:
          destinationPort: 53
issuer: CertFarm Ltd. # (optional) Verified crediential issuer

Rules Explained

Fundamentally, a behaviour claim is the collection of rules that describe the network activity we expect a device to exhibit/not exhibit. A rule can describe any combination of eth, ip4, tcp, or udp parameters for a given network event.

Certain behaviours are indicative of suspicious behaviour. Certain malware is known to communicate with specific servers, providing a form of guilt by association. Sources of these types behaviours can be downloaded from sites such as https://www.misp-project.org/. This would be a potential trusted source

Rules have a property malicious which is false by default. If malicious=false the behaviour is expected, if malicious=true the behaviour is suspicious. Practically, this allows you to triage the network behaviour of a device, and the router can implement a policy to accept/block traffic automatically based on the perceived risk level e.g.

Network Event	Category	Risk Level
Matches an expected rule	Expected	Low
Does not match any rule (not expected and not suspicious)	Unexpected	Medium
Matches a suspicious rule (`malicious=true`)	Suspicious	High

Inheriting Rules from Parent Behaviour Claims

Behaviours can inherit rules from other behaviour claims as a list of object referring to the id of the parent behaviour to inherit from and, optionally, the rules to inherit from that behaviour claim. By default, if only the id of the parent is given, all rules should be imported. In the GitHub implementation, you cannot import duplicate rules, the system will throw an error. The snippet from the example above shows several properties being inherited from a parent type.

  parents:
    - id: fc4d5a51-f985-4de1-a157-51ea9ca5e9c0 # Id of parent behaviour to inherit from
      # Specific rules to inherit from parent behaviour (optional) - all rules inherited by default
      rules:
        - from-ipv4-amazon-1
        - from-ipv4-amazon-4
        - from-ipv4-amazon-6

Device Vulnerability Assertion

About Vulnerability Claims

An assertion of device type vulnerability behaviour is a statement that says that a system vulnerability has been identified on all devices of the defined type.

Ideally this would contain a external link to the publicly documented vulnerability (a trusted external source like CVE or NVD)

Ideally this external link would include a back reference to the unambiguous device type

This type of information could be downloaded from a CVE database, if the declared vulnerability made use of a DeviceType formal link.

For Consideration

There may be an argument for defining a D3 Claim which corresponded to the full set of fields provided in vulnerability report. This would allow them to be signed and encrypted for some advanced workflow scenarios

Infer device instance vulnerability

If the device instance is recognised as a device type and the device type has a declared vulnerability than we can report that this instance is potentially vulnerable:

IF [device-instance] recognised as [device-type]
 AND IF [device-type] has [vulnerability]
  THEN ASSERT [device-instance] has [vulnerability]

It is then up to the policy of the router what to do with this vulnerability

JSON Schema

{
  "$id": "https://example.com/vuln.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "vulnerability",
  "description": "The vulnerability schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID for the vulnerability"
    },
    "vulnerability": {
      "type": "string",
      "description": "URL link to vulnerability details"
    }
  },
  "required": ["id"]
}

YAML Example

type: d3-device-type-vuln
credentialSubject:
  id: 7bb6ec6d-0514-4a2d-91b9-aed1cee34ef9  # GUID
  # Link to the source of a vulnerability preferably on NIST NVD, or CVE
  vulnerability: https://nvd.nist.gov/vuln/detail/CVE-2018-11581
issuer: CertFarm Ltd. # (optional) Verified crediential issuer

Sourcing Vulnerabilities

A system has been implemented to automatically source vulnerabilities from the NVD and CVE vulnerability databases.

Device Firmware Assertions

About Firmware Claims

Firmware claims allow manufacturers to assert information about the firmware versions a device can run. It may in the future reference vulnerbailities associated with that firmware version.

JSON Schema

{
  "$id": "https://example.com/firmware.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "behaviour",
  "description": "The device firmware schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "GUID for the firmware instance"
    },
    "type": {
      "type": "string",
      "format": "uuid",
      "description": "GUID for the device type for which this firmware applies"
    },
    "behaviour": {
      "type": "string",
      "format": "uuid",
      "description": "The behaviour name or id for this device type (optional)"
    },
    "versions": {
      "type": "string",
      "description": "The firmware version numbers for which this firmware behaviour is valid"
    }
  }
}

YAML Example

type: d3-firmware-assertion
credentialSubject:
  id: ffaf7fc3-52e1-41b3-80ea-f0cf5dc68933 # unique identifier
  type: 3ec73667-68e0-4f84-98f6-2b795aff5e05 # type for device for which firmware applies
  behaviour: 2de780eb-9f11-4f10-8a10-5ca62e2e71e6 # behaviour associated with this firmware
  # firmware versions which exhibit corresponding behaviour
  versions: ">=1.4,<4"
issuer: CertFarm Ltd.  # (optional) Verified crediential issuer

Inferred Claim Types

Infer: Device Instance

A device instance is inferred from D3Events activity and is a claim that a unique device exists.

JSON Schema

{
  "$id": "https://example.com/instance.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "instance",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "GUID for the instance"
    },
    "mac": {
      "type": "string",
      "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
      "description": "The device instance MAC address"
    },
    "primaryip": {
      "type": "string",
      "oneOf": [
        {"format": "ipv4"},
        {"format": "ipv6"}
      ],
      "description": "The device instance primary IP"
    },
    "secondaryip": {
      "type": "string",
      "oneOf": [
        {"format": "ipv4"},
        {"format": "ipv6"}
      ],
      "description": "The device instance secondary IP"
    },
    "name": {
      "type": "string",
      "description": "The device instance name"
    },
    "typeId": {
      "type": "string",
      "description": "The type GUID this instance inherits"
    }
  },
  "required": ["id"]
}

YAML Example

type: d3-device-instance-assertion
credentialSubject:
    id: DeviceID-GUID
    name: "My Device"
    mac: 00:00:5e:00:53:af
    primaryIp: 192.168.0.7 (optional)
    secondaryIp: 192.168.0.8 (optional)
 typeId: TypeClaim-guid (optional)
    # the device instance d3 claim is typtically issued by and signed by the router
issuer: Router-guid

A device assertion is typically made by the router when a new device is encountered.

The simplest implementation of this, assumes that MAC address are trusted and stable.

Under this assumption you can assert a new device, every time a new MAC address is encountered.

primaryIp and name are optional, and potentially ephemeral attributes.

We can a device instance update assertion to record the fact that that IP address or friendly name are updated.

An instance update claim is similar in structure to the assertion claim. The difference being the assertion should only be made for a fresh GUID, whereas the update claim should use a GUID that refers back to an originating assertion claim.

Alias

A device instance alias is a special case of assertion where we collapse to GUIDs into the same physical device

Infer Device Type

Based on the hierarchical nature of the device claims, and the specific nature of the device behaviours, it should be possible to infer the type of an connected instance of unknown type from its behaviour.

IF INSTANCE_BEHAVIOUR IS CLOSE TO DEVICE_BEHAVIOUR
THEN
 INSTANCE_TYPE := TYPE_ASSOCIATED_WITH_MATCHED_BEHAVIOUR

# OR
IF INSTANCE_MAC = MANUFACTURER_MAC_PATTERN
THEN
 INSTANCE_TYPE := MAIN_TYPE_FOR_MANUFACTURER

Infer (+ Assert?) Recognised Device

A device recognition inference is a claim that is individual device instance is of a specific device type.

This claim could be an assertion of an inference:

It is an assertion if the claim is that this device instance is of a type comes from an external system or external authority.
It is an inference if the claim can be logically or statistically asserted from the information present in the aggregate claims available at the D3 agent

    type:    d3-device-recognised
    credentialSubject:
     d3instance:  DeviceID (GUID)
  d3type:   www.nquiringminds.com/747775776 (URI)
        time:   when recognised
    # a d3 type can be issued by many parties
    issuer:   (agent | user | orgs)

Possible device recognition implementations

User recognition

The user may manually recognise the device, by looking at it, entering data in some fields into a form. This could be done by a config page on the router, or an accompanying mobile application

User assisted recognition

This method could be streamlined by issuing QR codes on device packaging that link to manufacture supplies statements (but the user is still authorising the recognition event). The user is making the claim, but based on information the manufacture as provided

External

IRA.ORG - QR Code that interworks with MUD and MAC addresss

Manufacture MUD recognition

The router may make recognition assertion based on a valid MUD URI issued by the device.

The MUD is issued by the manufactuer (in most cases)

But the router needs to intercept the URI in the DHCP request, and validate the document

Manufacture FIDO recognition

The router (or an application, or a service) may intercept a FIDO device attestation token which can be reconciled with the device type.

Manufacture Matter recognition

The router (or an application, or a service) may intercept a MATTER device attestation token which can be reconciled with the device type.

Manufacture MAC recognition

Manufacture HTTPS certificate recognition

Smart Agent Recognition

Smart-Agents: there are a whole host of local application or cloud services that could automagically/partially recognise a device based on MAC address. E.g. extracting the vendor from the MAC address is a weak method of crudely mapping to a device type (device type is manufacture only).

Alternatively a smart agent may categorise a device as IoT vs Non IoT device based on an historical analysis of its network traffic. For example

IoT device is more likely to receive traffic
IoT device is more likely to participate in internal network traffic
IoT device is likely to only "speak to" as small number of destinations
IoT device is more likely to have highly regularised network patterns

Infer observed instance behaviour

This is similar to a device type behaviour assertion with a critical differences. This is statement of what the D3 Agent has seen an individual device instance do, not a generalised device type. Its based on observation not definitions.

    type:  d3-device-instance-behaviour
    credentialSubject:
    d3instance: DeviceID (GUID)
    bevaviour: https://www.iotsecurityfoundation.org?b&dev=343242423
        time: when observed (range)
    # this is an ovservation and can only be made by the router
    issuer: (router)

This information is derived from the D3Events activity.

These statements are created dynamically by the router. They can be used a number of ways.

1) They can be compared to device-type behaviour to determine anomalies. 2) They can be submitted to a D3 authority (locally or externally) as evidence for prospective new behaviour descriptions or to update existing behaviour definitions.

Infer behaviour of instance based on type behaviour

Simply if the router has identified a device instance A and that device instance is been recognised as device type X, and type X has a defined behaviour Z then the router could assert that this device instance A must have behaviour Z.

IF [device-instance] recognised as [device-type]
 AND IF [device-type] has [behaviour]
  THEN ASSERT [device-instance] has [behaviour]

What you do when an device instance has a defined behaviour could be varied (see below )

This in example of a basic deductive inference: the instance should inherit the behaviour property of the type.

If for any reason this claim is provably wrong, then either:

The type behaviour is incorrect
OR the instance is not of this type

Infer a device type behavioural description

This is a different way of asserting device type behaviours.

This behavioural description is based on combing the real word behaviours or one or more instances, which we know to be of the same type and making a probable insertion of a type behaviour

IF one or more [device-instance] recognised as [device-type]
 AND [device-instance] has [behaviour]
  THEN COMBINE ALL [behaviours] as [COMBINED BEHAVIOUR]
   ASSERT [device-type] has [COMBINED BEHAVIOUR]

This is an example of a inductive inference

Constrain behaviour

If we have asserted that an individual device instance has a defined behaviour, then we can ask DCon to physically limit this instance the activity of this device.

Technically this would be achieved by calling the BindDescription method of DCon using the device instacne GUID and supplying the behaviour as a string.

Infer anomalous behaviour

Alternatively (or in addition to) if a device instance attempts to communicate outside of its asserted behaviour, we could raise and anomaly assertion

type:    d3-device-instance-anomoly
credentialSubject:
    d3instance:  DeviceID (GUID)
    reason:   text to explain why anomoly was raided  (string)
    # this is an ovservation and can only be made by the router
issuer:   (router)

Infer device instance suspicious behaviour

Where the D3Events derived behaviour matches the asserted fingerprint - we can raise a claim that this device is acting suspiciously.

Actions

These need transferring into issues.

improve the YAML specification method - is it correct?
ideally create YAML/JSON auto converter
ideally create Schema representation to set along side each example
add example for vulnerability probe suspected activity
look at ncsc scripts - can we fold in?
make clear that the examples heuristics are that only.

For ease of use and editing, a D3 behaviour will be expressed as a compact YAML file.

These YAML files should be a logical subset of IETF/MUD referenced YANG files

TODO

We write convertors to prove that a YANG file can be produced from a D3 Behaviour YAML https://iotanalytics.unsw.edu.au/mud/withingsbabymonitorMud.json

Examples for YANG and MUD

Uses this area to record useful YANG/MUD references

Asserted Claim Types​

Asserted Claim Relationships​

D3 Claim Meta​

JSON Schema​

YAML D3 Claim Example​

Device Type Assertion​

About Type Claims​

Sources of device type assertions​

JSON Schema​

YAML Example​

Linking a Behaviour​

Linking Vulnerabilities and Firmware​

Inheriting Properties from Parent Type Claims​

Embedding Hierarchy Statements​

Alias​

Device Behaviour Assertion​

About Behaviour Claims​

JSON Schema​

YAML Example with Rules​

Rules Explained​

Inheriting Rules from Parent Behaviour Claims​

Device Vulnerability Assertion​

About Vulnerability Claims​

Infer device instance vulnerability​

JSON Schema​

YAML Example​

Sourcing Vulnerabilities​

Device Firmware Assertions​

About Firmware Claims​

JSON Schema​

YAML Example​

Inferred Claim Types​

Infer: Device Instance​

JSON Schema​

YAML Example​

Infer Device Type​

Infer (+ Assert?) Recognised Device​

Possible device recognition implementations​

User recognition​

User assisted recognition​

Manufacture MUD recognition​

Manufacture FIDO recognition​

Manufacture Matter recognition​

Manufacture MAC recognition​

Manufacture HTTPS certificate recognition​

Smart Agent Recognition​

Infer observed instance behaviour​

Infer behaviour of instance based on type behaviour​

Infer a device type behavioural description​

Constrain behaviour​

Infer anomalous behaviour​

Infer device instance suspicious behaviour​

Actions​

Examples for YANG and MUD​

Asserted Claim Types

Asserted Claim Relationships

D3 Claim Meta

JSON Schema

YAML D3 Claim Example

Device Type Assertion

About Type Claims

Sources of device type assertions

JSON Schema

YAML Example

Linking a Behaviour

Linking Vulnerabilities and Firmware

Inheriting Properties from Parent Type Claims

Embedding Hierarchy Statements

Alias

Device Behaviour Assertion

About Behaviour Claims

JSON Schema

YAML Example with Rules

Rules Explained

Inheriting Rules from Parent Behaviour Claims

Device Vulnerability Assertion

About Vulnerability Claims

Infer device instance vulnerability

JSON Schema

YAML Example

Sourcing Vulnerabilities

Device Firmware Assertions

About Firmware Claims

JSON Schema

YAML Example

Inferred Claim Types

Infer: Device Instance

JSON Schema

YAML Example

Infer Device Type

Infer (+ Assert?) Recognised Device

Possible device recognition implementations

User recognition

User assisted recognition

Manufacture MUD recognition

Manufacture FIDO recognition

Manufacture Matter recognition

Manufacture MAC recognition

Manufacture HTTPS certificate recognition

Smart Agent Recognition

Infer observed instance behaviour

Infer behaviour of instance based on type behaviour

Infer a device type behavioural description

Constrain behaviour

Infer anomalous behaviour

Infer device instance suspicious behaviour

Actions

Examples for YANG and MUD